BBS Toolkit/BBS Toolkit.iso/qbbs/rachad10.zip/CHGADDR.DOC

Text File | 1990-08-05 | 18KB | 643 lines

                                    ChgAddr V1.0                                    ChgAddr V1.0
                     Network Mail Re-Addresser for RemoteAccess                     Network Mail Re-Addresser for RemoteAccess




                             by Marc A. Shannon, 129/45                             by Marc A. Shannon, 129/45
                                   August 5, 1990                                   August 5, 1990










                                      Chapter 1                                      Chapter 1

                                    Introduction                                    Introduction


          ChgAddr is a program  which  can  be  used with your RemoteAccess
          system  to  "correct"  the  source  or  destination  Network Mail
          address of any message in your RA message base in the first board
          listed as being for "NetMail".  (See page 26 of  the RemoteAccess
          documentation for information on  setting  up  a message area for
          use with Network Mail.)

          Using  a simple configuration file, you  can  tell  ChgAddr  what
          messages you want "altered" to suit your network setup.   You can
          include  multiple  rules  to  suit  as many changes as you  need.
          There is no limit on the number of rules you  can  include in the
          configuration  file except for the limit  of  your  system's  (or
          window's) memory size.

          As  with  most,  if not all, other software products available on
          FidoNet, no guarantee is given  to the stability of this program.
          It might trash your message base,  but  it probably won't.  All I
          know is that it works on my system.

          The archive as sent out on SDSRA includes five files:

                 CHGADDR.EXE  The actual executable program

                 SAMPLE.CFG   A  sample configuration file which shows  use
                              of the different possible rules

                 CHGADDR.DOC  The documentation formatted for any  standard
                              printer

                 CHGADDR.EPS  The   documentation   formatted   for   Epson
                              printers  (or  those which  emulate  standard
                              Epson MX-80 codes)

                 README       A brief summary of what ChgAddr does

          This program is somewhat ShareWare.   If  you use it and you like
          it, you don't owe anything.   If  you  would like me to know that
          you really like it, you may send in a small  amount  of money (no
          more than $5 please) to:




               Marc Shannon
               ChgAddr Donation
               CMU P. O. Box 257
               Pittsburgh, PA  15213-3890

          If you do send $5, I will, first of all, be interested in writing
          future programs that  work  with RemoteAccess, and also will make
          sure that I send you any new versions of ChgAddr  as  well as any
          new  RA support programs that I write.    Alternatively,  if  you
          would like, just send me a NetMail message and I'll be happy with
          that.









































                                        - 2 -










                                      Chapter 2                                      Chapter 2

                            Requirements and restrictions                            Requirements and restrictions


          ChgAddr was written on a 80386-SX system running  MS-DOS  3.3 and
          RemoteAccess 0.04a, but should work on any MS-DOS 3.x system with
          RemoteAccess 0.03  or later (not including 1.00 which may require
          a rewrite of the message-base structures).  ChgAddr is written in
          C using  the  Turbo  C  2.0  compiler.   (If you're interested in
          seeing my RASTRUCT.H file, you can FREQ it from 129/45.)

          In order to  run  ChgAddr,  you  only need to follow the standard
          setup   procedures   for   RemoteAccess   and  then  create  your
          configuration  file,  CHGADDR.CFG.     ChgAddr  will  check  your
          environment for the RA variable.   If  found, it will use this to
          find your RemoteAccess configuration and then  use  your message-
          base path listed in there. If the RA environment variable  is not
          found, ChgAddr will do all its work from the current directory.

          You should place your CHGADDR.CFG  file in the directory that the
          RA environment variable points to.   (If  it is not found in that
          directory, the current directory is also checked.)

          ChgAddr is only  16K  and  should  work fine in even the smallest
          memory configuration.  (You may need more memory  for  ChgAddr to
          run if you have zillions of rewrite rules, though.)

          At  its  peak,  ChgAddr only opens 4 files concurrently, which is
          less than RemoteAccess opens.  ChgAddr will tell you, however, if
          it  is  unable  to open a file needed for proper operation.  When
          running,  it  always  opens the files with sharing options so it,
          theoretically, could  be run in a multi-line situation.  Standard
          DOS locks are taken out on the records being modified  to prevent
          accidental conflicts.  This only works if any other programs with                                      only
          access the message-base use these locking routines.

          It should be mentioned  that  this release of ChgAddr DOES NOT do                                                                DOES NOT
          anything with respect to points.  Any point  values  specified in
          the configuration file are flagged as invalid.






                                        - 3 -










                                      Chapter 3                                      Chapter 3

                             Configuration (rules) file                             Configuration (rules) file


          This  is where the guts of the  ChgAddr  configuration  file  are
          explained.

          First off, your configuration file should be placed either in the
          directory where you plan to  run ChgAddr during your normal batch
          file  processing  of  exporting  NetMail  messages  or   in  your
          RemoteAccess system file  directory  (as defined by, and I'll say
          it again, your RA environment variable).

          The ChgAddr configuration  file  is a "free-format" file with one
          small exception.  You  may  include comments on any line when you
          use a semicolon (;) in front of your comment text.  The exception
          to  the   "free-format"  is  that  blank  lines  have  a  special
          significance.

          Your configuration file  can  contain many "rules", each of which
          can specify a certain address  match  with  certain  rewrites for
          those matches.  Between each rule, you need to have a blank line.
          You may include as many rewrite rules in  the  configuration file
          as you need or want.  In processing, ChgAddr will only  apply the
          FIRST rewrite rule which matches the particular message.          FIRST

          Each rewrite rule can include  up to four clauses: Old-From, Old-
          To, New-From, and New-To.    The "old" clauses may contain one or
          more  network  addresses  while  the  "new"  clauses  should only
          contain one address.

          A fully specified rule could be shown as:

               [Old-From addr-list]
               [Old-To addr-list]
               [New-From addr]
               [New-To addr]

          where the "addr-list" would  be  one  or more addresses, possibly
          including  the  use  of  "All"  or "Except" phrases.  The  format
          follows (as closely as possible) the format used  by  many mailer
          programs which allow for multiple address specifications.  "addr-
          list"  may  span  multiple lines provided that there is no clause


                                        - 4 -




          keyword  in  the  middle  and  that  there  isn't  a  blank  line
          separating the addresses. You'd  probably  better  check  out the
          SAMPLE.CFG file for a  better  idea of what the address lists can
          look like.

          Let's examine the use  of  the  Old-From  clause.  (The following
          examples  are  taken  from  the  first  rule  in  the  SAMPLE.CFG
          configuration file provided with the ChgAddr V1.0 archive.)

               Old-From 1:1/6

          This will match any message  which has its NetMail origin address
          as 1:1/6.

               Old-To All Except 1:1/0 1 2 3 4 5
                                 6 8 10 11 12 102
                                 103 201 129/40

          This will match  any  message  which  is  not going to one of the
          specified nodes in net 1:1 or going to 1:129/40.

          Note that for a successful match of any message,  both  the  Old-
          From and Old-To clauses must  match successfully if they are both
          supplied. (A rule with no "old" clauses will never  match  as  in
          the second example in SAMPLE.CFG.)

               New-From 1:129/45

          This is an example of an action clause.    If  a  message matched
          both the above  Old-From  and Old-To clauses, it's origin address
          would be changed to be 1:129/45.

          If  we  wanted  to include other rewrite rules, they would follow
          this one after a blank line in a similar manner to this example.


















                                        - 5 -










                                      Chapter 4                                      Chapter 4

                                 Method of operation                                 Method of operation


          Here's a play-by-play list of exactly what ChgAddr does.

            1.  ChgAddr finds  out what your RA environment variable is set
                to.  If it is undefined, the current directory is  used for
                all the system file processing.

            2.  CONFIG.RA is then read to load  the  message-base directory
                name as well as your system's primary network address.

            3.  Then, MESSAGES.RA  is  checked  for  your  systems  NetMail
                board.   Note that ChgAddr only looks  to  find  the  first
                message area which  is  marked for NetMail.  Any subsequent
                ones are ignored!

            4.  At this point, your configuration file is read in.  ChgAddr
                first checks the  current  directory and then looks in your
                RA system  directory  (as  defined  by  the  RA environment
                variable,   not   the   directory   specified  in  your  RA
                configuration file).

            5.  Once your configuration file has been parsed  and converted
                to  internal  rules,   ChgAddr  opens  up  MSGIDX.BBS  (for
                reading) and MSGHDR.BBS (for reading and possible writing).
                MSGINFO.BBS  is  read  in to get the statistics on how many
                messages are on the NetMail board.

            6.  MSGIDX.BBS is scanned for any  messages  which  are  on the
                NetMail board.  When one is found, MSGHDR.BBS  is  read for
                that particular record.  These  conditions  are  checked to
                see if a message qualifies for an address rewrite:
                   -  The message is not deleted

                   -  The message is marked as "pending export"

                   -  The messages source and destination address match one
                      of the rules listed in the ChgAddr configuration file





                                        - 6 -




            7.  If the message's address needs  to  be  rewritten,  the new
                addresses are loaded  in  and the message header is written
                back to the MSGHDR.BBS file.

            8.  Steps 6 and 7 are repeated until all the  messages  on  the
                NetMail board have been checked.














































                                        - 7 -










                                      Chapter 5                                      Chapter 5

                              Error levels and messages                              Error levels and messages


          Only three errorlevels are used by ChgAddr.   They  are described
          below.

          Errorlevel 1 indicates that a  necessary system file could not be
          opened.  A system error message is given with  this  showing  the
          particular file and the reason why it could not be opened.

          Errorlevel 2 is used when an I/O error occurs during  the reading
          or writing of one of the system files.

          Errorlevel  3  is  for  ChgAddr's  errors.  These  are  generally
          configuration  errors.    A  message  is  printed  on the  screen
          explaining the problem.

          Since the first two errorlevels  represent  standard  DOS errors,
          the error messages printed on  the console should be fairly self-
          explanatory  (or  you  can use your DOS reference manual for more
          information).   Errorlevel 3 could include  a  number  of  errors
          including:

               Syntax error on line #
               While ChgAddr was parsing your configuration file,  it could
               not understand  something  on  the  line  number  specified.
               Check   your  configuration  file  for  possible  typos   or
               incorrect network address punctuation.

               Net address format error on line #
               A network address  has  not been completely specified.  This
               could be from using something  similar  to  "1:13"  where no
               node  number  has  been  specified;  you   may   have  meant
               "1:13/All".

               ALL cannot be used here on line #
               You have used the "All" phrase in an invalid context.   This
               could  be  in  "1:129/45 All" where you  should  simply  say
               "1:129/All".  Also, you cannot use "All" in your new-rewrite
               lines (New-From and New-To).




                                        - 8 -




               Keyword missing or invalid ("keyword") on line #
               The keyword specified inside the  quotation  marks  has been
               flagged as  invalid.    Check  for  misspellings  and proper
               configuration file keywords.  It's  also  possible  that the
               keyword was specified at  an  incorrect  time (such as using
               "All" without specifying which pattern it is to match).

               Unrecognized keyword ("keyword") on line #
               You have used a  keyword  in the right context, but it isn't
               one  that ChgAddr knows about.  Check  the  chapter  on  the
               configuration file  to ensure that you are using the correct
               format.








































                                        - 9 -










                                      Chapter 6                                      Chapter 6

                                       Support                                       Support


          Support?  You've got to be kidding!  Ha ha ha ha ha!

          Well, actually, like most authors,  I  am  interested  in finding
          (and killing) bugs.  If you do have problems  with  this  program
          and just can't seem to get it to  work  for  you,  send a copy of
          your CHGADDR.CFG file along with a description of  the  error (or
          non-error) that you're getting and I'll see what I can do.

          (In order to prevent  file  name  duplication, please rename your
          configuration when sending it to something that I will be able to
          identify with your node.)

          My  system,  1:129/45,  is  reachable  24  hours  a  day  running
          FrontDoor all that time.  THIS  BOARD  IS  NOT A SUPPORT BBS.  If
          you send me, via NetMail, your question or problem, I will answer
          it  to  the  best of my ability, but I don't  have  any  suitable
          online conferences or files that will help you.
























                                        - 10 -








                                   Table of Contents                                   Table of Contents





               Chapter 1  Introduction                               1

               Chapter 2  Requirements and restrictions              3

               Chapter 3  Configuration (rules) file                 4

               Chapter 4  Method of operation                        6

               Chapter 5  Error levels and messages                  8

               Chapter 6  Support                                   10































                                          i